home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 2000 July: Mac OS SDK / Dev.CD Jul 00 SDK2.toast / Development Kits / Cross Platform / QuickTime 4.1.2 Windows SDK / CIncludes / AppleGuide.h < prev    next >
Encoding:
C/C++ Source or Header  |  2000-04-12  |  14.8 KB  |  549 lines  |  [TEXT/R*ch]
  1. /*
  2.      File:        AppleGuide.h
  3.  
  4.      Contains:    Apple Guide Interfaces.
  5.  
  6.      Version:    Technology:    Mac OS 8
  7.                  Release:    QuickTime 4.1
  8.  
  9.      Copyright:    (c)1994-1999 by Apple Computer, Inc., all rights reserved.
  10.  
  11.      Bugs?:        For bug reports, consult the following page on
  12.                  the World Wide Web:
  13.  
  14.                      http://developer.apple.com/bugreporter/
  15.  
  16. */
  17. #ifndef __APPLEGUIDE__
  18. #define __APPLEGUIDE__
  19.  
  20. #ifndef __MACTYPES__
  21.     #include <MacTypes.h>
  22. #endif
  23.  
  24. #ifndef __APPLEEVENTS__
  25.     #include <AppleEvents.h>
  26. #endif
  27.  
  28. #ifndef __FILES__
  29.     #include <Files.h>
  30. #endif
  31.  
  32.  
  33.  
  34.  
  35. #if PRAGMA_ONCE
  36. #pragma once
  37. #endif
  38.  
  39. #ifdef __cplusplus
  40. extern "C" {
  41. #endif
  42.  
  43. #if PRAGMA_IMPORT
  44. #pragma import on
  45. #endif
  46.  
  47. #if PRAGMA_STRUCT_ALIGN
  48.     #pragma options align=mac68k
  49. #elif PRAGMA_STRUCT_PACKPUSH
  50.     #pragma pack(push, 2)
  51. #elif PRAGMA_STRUCT_PACK
  52.     #pragma pack(2)
  53. #endif
  54.  
  55. /* Types*/
  56. typedef UInt32                             AGRefNum;
  57. typedef UInt32                             AGCoachRefNum;
  58. typedef UInt32                             AGContextRefNum;
  59.  
  60. struct AGAppInfo {
  61.     AEEventID                         eventId;
  62.     long                             refCon;
  63.     void *                            contextObj;                    /* private system field*/
  64. };
  65. typedef struct AGAppInfo                AGAppInfo;
  66. typedef AGAppInfo *                        AGAppInfoPtr;
  67. typedef AGAppInfoPtr *                    AGAppInfoHdl;
  68. typedef CALLBACK_API( OSErr , CoachReplyProcPtr )(Rect *pRect, Ptr name, long refCon);
  69. typedef CALLBACK_API( OSErr , ContextReplyProcPtr )(Ptr pInputData, Size inputDataSize, Ptr *ppOutputData, Size *pOutputDataSize, AGAppInfoHdl hAppInfo);
  70. typedef STACK_UPP_TYPE(CoachReplyProcPtr)                         CoachReplyUPP;
  71. typedef STACK_UPP_TYPE(ContextReplyProcPtr)                     ContextReplyUPP;
  72. #if OPAQUE_UPP_TYPES
  73.     EXTERN_API(CoachReplyUPP)
  74.     NewCoachReplyUPP               (CoachReplyProcPtr        userRoutine);
  75.  
  76.     EXTERN_API(ContextReplyUPP)
  77.     NewContextReplyUPP               (ContextReplyProcPtr        userRoutine);
  78.  
  79.     EXTERN_API(void)
  80.     DisposeCoachReplyUPP           (CoachReplyUPP            userUPP);
  81.  
  82.     EXTERN_API(void)
  83.     DisposeContextReplyUPP           (ContextReplyUPP            userUPP);
  84.  
  85.     EXTERN_API(OSErr)
  86.     InvokeCoachReplyUPP               (Rect *                    pRect,
  87.                                     Ptr                        name,
  88.                                     long                    refCon,
  89.                                     CoachReplyUPP            userUPP);
  90.  
  91.     EXTERN_API(OSErr)
  92.     InvokeContextReplyUPP           (Ptr                        pInputData,
  93.                                     Size                    inputDataSize,
  94.                                     Ptr *                    ppOutputData,
  95.                                     Size *                    pOutputDataSize,
  96.                                     AGAppInfoHdl            hAppInfo,
  97.                                     ContextReplyUPP            userUPP);
  98.  
  99. #else
  100.     enum { uppCoachReplyProcInfo = 0x00000FE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes) */
  101.     enum { uppContextReplyProcInfo = 0x0000FFE0 };                     /* pascal 2_bytes Func(4_bytes, 4_bytes, 4_bytes, 4_bytes, 4_bytes) */
  102.     #define NewCoachReplyUPP(userRoutine)                             (CoachReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppCoachReplyProcInfo, GetCurrentArchitecture())
  103.     #define NewContextReplyUPP(userRoutine)                         (ContextReplyUPP)NewRoutineDescriptor((ProcPtr)(userRoutine), uppContextReplyProcInfo, GetCurrentArchitecture())
  104.     #define DisposeCoachReplyUPP(userUPP)                             DisposeRoutineDescriptor(userUPP)
  105.     #define DisposeContextReplyUPP(userUPP)                         DisposeRoutineDescriptor(userUPP)
  106.     #define InvokeCoachReplyUPP(pRect, name, refCon, userUPP)         (OSErr)CALL_THREE_PARAMETER_UPP((userUPP), uppCoachReplyProcInfo, (pRect), (name), (refCon))
  107.     #define InvokeContextReplyUPP(pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo, userUPP)  (OSErr)CALL_FIVE_PARAMETER_UPP((userUPP), uppContextReplyProcInfo, (pInputData), (inputDataSize), (ppOutputData), (pOutputDataSize), (hAppInfo))
  108. #endif
  109. /* support for pre-Carbon UPP routines: NewXXXProc and CallXXXProc */
  110. #define NewCoachReplyProc(userRoutine)                             NewCoachReplyUPP(userRoutine)
  111. #define NewContextReplyProc(userRoutine)                         NewContextReplyUPP(userRoutine)
  112. #define CallCoachReplyProc(userRoutine, pRect, name, refCon)    InvokeCoachReplyUPP(pRect, name, refCon, userRoutine)
  113. #define CallContextReplyProc(userRoutine, pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo) InvokeContextReplyUPP(pInputData, inputDataSize, ppOutputData, pOutputDataSize, hAppInfo, userRoutine)
  114. /* Constants*/
  115.  
  116.  
  117. enum {
  118.     kAGDefault                    = 0,
  119.     kAGFrontDatabase            = 1,
  120.     kAGNoMixin                    = (-1)
  121. };
  122.  
  123.  
  124. enum {
  125.     kAGViewFullHowdy            = 1,                            /* Full-size Howdy*/
  126.     kAGViewTopicAreas            = 2,                            /* Full-size Topic Areas*/
  127.     kAGViewIndex                = 3,                            /* Full-size Index Terms*/
  128.     kAGViewLookFor                = 4,                            /* Full-size Look-For (Search)*/
  129.     kAGViewSingleHowdy            = 5,                            /* Single-list-size Howdy*/
  130.     kAGViewSingleTopics            = 6                                /* Single-list-size Topics*/
  131. };
  132.  
  133.  
  134. enum {
  135.     kAGFileMain                    = FOUR_CHAR_CODE('poco'),
  136.     kAGFileMixin                = FOUR_CHAR_CODE('mixn')
  137. };
  138.  
  139. /* To test against AGGetAvailableDBTypes*/
  140. enum {
  141.     kAGDBTypeBitAny                = 0x00000001,
  142.     kAGDBTypeBitHelp            = 0x00000002,
  143.     kAGDBTypeBitTutorial        = 0x00000004,
  144.     kAGDBTypeBitShortcuts        = 0x00000008,
  145.     kAGDBTypeBitAbout            = 0x00000010,
  146.     kAGDBTypeBitOther            = 0x00000080
  147. };
  148.  
  149.  
  150.  
  151. typedef UInt16                             AGStatus;
  152. /* Returned by AGGetStatus*/
  153. enum {
  154.     kAGIsNotRunning                = 0,
  155.     kAGIsSleeping                = 1,
  156.     kAGIsActive                    = 2
  157. };
  158.  
  159. /* Flags used in AGOpen, AGOpenWithSearch, AGOpenWithView*/
  160. enum {
  161.     kHelpViewerSearchAll        = (1 << 0)
  162. };
  163.  
  164. typedef UInt16                             AGWindowKind;
  165. /* Returned by AGGetFrontWindowKind*/
  166. enum {
  167.     kAGNoWindow                    = 0,
  168.     kAGAccessWindow                = 1,
  169.     kAGPresentationWindow        = 2
  170. };
  171.  
  172. /* Error Codes*/
  173.  
  174. /* Not an enum, because other OSErrs are valid.*/
  175. typedef SInt16                             AGErr;
  176. /* Apple Guide error codes*/
  177. enum {
  178.                                                                 /* -------------------- Apple event reply codes*/
  179.     kAGErrUnknownEvent            = -2900,
  180.     kAGErrCantStartup            = -2901,
  181.     kAGErrNoAccWin                = -2902,
  182.     kAGErrNoPreWin                = -2903,
  183.     kAGErrNoSequence            = -2904,
  184.     kAGErrNotOopsSequence        = -2905,
  185.     kAGErrReserved06            = -2906,
  186.     kAGErrNoPanel                = -2907,
  187.     kAGErrContentNotFound        = -2908,
  188.     kAGErrMissingString            = -2909,
  189.     kAGErrInfoNotAvail            = -2910,
  190.     kAGErrEventNotAvailable        = -2911,
  191.     kAGErrCannotMakeCoach        = -2912,
  192.     kAGErrSessionIDsNotMatch    = -2913,
  193.     kAGErrMissingDatabaseSpec    = -2914,
  194.     kAGMissingSequenceMap        = -2915,                        /* -------------------- Coach's Chalkboard reply codes*/
  195.     kAGErrItemNotFound            = -2925,
  196.     kAGErrBalloonResourceNotFound = -2926,
  197.     kAGErrChalkResourceNotFound    = -2927,
  198.     kAGErrChdvResourceNotFound    = -2928,
  199.     kAGErrAlreadyShowing        = -2929,
  200.     kAGErrBalloonResourceSkip    = -2930,
  201.     kAGErrItemNotVisible        = -2931,
  202.     kAGErrReserved32            = -2932,
  203.     kAGErrNotFrontProcess        = -2933,
  204.     kAGErrMacroResourceNotFound    = -2934,                        /* -------------------- API reply codes*/
  205.     kAGErrAppleGuideNotAvailable = -2951,
  206.     kAGErrCannotInitCoach        = -2952,
  207.     kAGErrCannotInitContext        = -2953,
  208.     kAGErrCannotOpenAliasFile    = -2954,
  209.     kAGErrNoAliasResource        = -2955,
  210.     kAGErrDatabaseNotAvailable    = -2956,
  211.     kAGErrDatabaseNotOpen        = -2957,
  212.     kAGErrMissingAppInfoHdl        = -2958,
  213.     kAGErrMissingContextObject    = -2959,
  214.     kAGErrInvalidRefNum            = -2960,
  215.     kAGErrDatabaseOpen            = -2961,
  216.     kAGErrInsufficientMemory    = -2962
  217. };
  218.  
  219. /* Events*/
  220.  
  221. /* Not an enum because we want to make assignments.*/
  222. typedef UInt32                             AGEvent;
  223. /* Handy events for AGGeneral.*/
  224. enum {
  225.                                                                 /* Panel actions (Require a presentation window).*/
  226.     kAGEventDoCoach                = FOUR_CHAR_CODE('doco'),
  227.     kAGEventDoHuh                = FOUR_CHAR_CODE('dhuh'),
  228.     kAGEventGoNext                = FOUR_CHAR_CODE('gonp'),
  229.     kAGEventGoPrev                = FOUR_CHAR_CODE('gopp'),
  230.     kAGEventHidePanel            = FOUR_CHAR_CODE('pahi'),
  231.     kAGEventReturnBack            = FOUR_CHAR_CODE('gobk'),
  232.     kAGEventShowPanel            = FOUR_CHAR_CODE('pash'),
  233.     kAGEventTogglePanel            = FOUR_CHAR_CODE('patg')
  234. };
  235.  
  236. /* Functions*/
  237.  
  238. /*
  239.    AGClose
  240.    Close the database associated with the AGRefNum.
  241. */
  242.  
  243. EXTERN_API( AGErr )
  244. AGClose                            (AGRefNum *                refNum)                                TWOWORDINLINE(0x7011, 0xAA6E);
  245.  
  246. /*
  247.    AGGeneral
  248.    Cause various events to happen.
  249. */
  250.  
  251. EXTERN_API( AGErr )
  252. AGGeneral                        (AGRefNum                 refNum,
  253.                                  AGEvent                 theEvent)                            TWOWORDINLINE(0x700D, 0xAA6E);
  254.  
  255. /*
  256.    AGGetAvailableDBTypes
  257.    Return the database types available for this application.
  258. */
  259.  
  260. EXTERN_API( UInt32 )
  261. AGGetAvailableDBTypes            (void)                                                        TWOWORDINLINE(0x7008, 0xAA6E);
  262.  
  263. /*
  264.    AGGetFrontWindowKind
  265.    Return the kind of the front window.
  266. */
  267.  
  268. EXTERN_API( AGWindowKind )
  269. AGGetFrontWindowKind            (AGRefNum                 refNum)                                TWOWORDINLINE(0x700C, 0xAA6E);
  270.  
  271. /*
  272.    AGGetFSSpec
  273.    Return the FSSpec for the AGRefNum.
  274. */
  275.  
  276. EXTERN_API( AGErr )
  277. AGGetFSSpec                        (AGRefNum                 refNum,
  278.                                  FSSpec *                fileSpec)                            TWOWORDINLINE(0x700F, 0xAA6E);
  279.  
  280. /*
  281.    AGGetStatus
  282.    Return the status of Apple Guide.
  283. */
  284.  
  285. EXTERN_API( AGStatus )
  286. AGGetStatus                        (void)                                                        TWOWORDINLINE(0x7009, 0xAA6E);
  287.  
  288. /*
  289.    AGInstallCoachHandler
  290.    Install a Coach object location query handler.
  291. */
  292.  
  293. EXTERN_API( AGErr )
  294. AGInstallCoachHandler            (CoachReplyUPP             coachReplyProc,
  295.                                  long                     refCon,
  296.                                  AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7012, 0xAA6E);
  297.  
  298. /*
  299.    AGInstallContextHandler
  300.    Install a context check query handler.
  301. */
  302.  
  303. EXTERN_API( AGErr )
  304. AGInstallContextHandler            (ContextReplyUPP         contextReplyProc,
  305.                                  AEEventID                 eventID,
  306.                                  long                     refCon,
  307.                                  AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7013, 0xAA6E);
  308.  
  309. /*
  310.    AGIsDatabaseOpen
  311.    Return true if the database associated with the AGRefNum is open.
  312. */
  313.  
  314. EXTERN_API( Boolean )
  315. AGIsDatabaseOpen                (AGRefNum                 refNum)                                TWOWORDINLINE(0x7006, 0xAA6E);
  316.  
  317. /*
  318.    AGOpen
  319.    Open a guide database.
  320. */
  321.  
  322. EXTERN_API( AGErr )
  323. AGOpen                            (ConstFSSpecPtr         fileSpec,
  324.                                  UInt32                 flags,
  325.                                  Handle                 mixinControl,
  326.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7001, 0xAA6E);
  327.  
  328. /*
  329.    AGOpenWithSearch
  330.    Open a guide database and preset a search string.
  331. */
  332.  
  333. EXTERN_API( AGErr )
  334. AGOpenWithSearch                (ConstFSSpecPtr         fileSpec,
  335.                                  UInt32                 flags,
  336.                                  Handle                 mixinControl,
  337.                                  ConstStr255Param         searchString,
  338.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7002, 0xAA6E);
  339.  
  340. /*
  341.    AGOpenWithSequence
  342.    Open a guide database and display a presentation window sequence.
  343. */
  344.  
  345. EXTERN_API( AGErr )
  346. AGOpenWithSequence                (ConstFSSpecPtr         fileSpec,
  347.                                  UInt32                 flags,
  348.                                  Handle                 mixinControl,
  349.                                  short                     sequenceID,
  350.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7004, 0xAA6E);
  351.  
  352. /*
  353.    AGOpenWithView
  354.    Open a guide database and override the default view.
  355. */
  356.  
  357. EXTERN_API( AGErr )
  358. AGOpenWithView                    (ConstFSSpecPtr         fileSpec,
  359.                                  UInt32                 flags,
  360.                                  Handle                 mixinControl,
  361.                                  short                     viewNum,
  362.                                  AGRefNum *                resultRefNum)                        TWOWORDINLINE(0x7005, 0xAA6E);
  363.  
  364. /*
  365.    AGQuit
  366.    Make Apple Guide quit.
  367. */
  368.  
  369. EXTERN_API( AGErr )
  370. AGQuit                            (void)                                                        TWOWORDINLINE(0x7010, 0xAA6E);
  371.  
  372. /*
  373.    AGRemoveCoachHandler
  374.    Remove the Coach object location query handler.
  375. */
  376.  
  377. EXTERN_API( AGErr )
  378. AGRemoveCoachHandler            (AGCoachRefNum *        resultRefNum)                        TWOWORDINLINE(0x7014, 0xAA6E);
  379.  
  380. /*
  381.    AGRemoveContextHandler
  382.    Remove the context check query handler.
  383. */
  384.  
  385. EXTERN_API( AGErr )
  386. AGRemoveContextHandler            (AGContextRefNum *        resultRefNum)                        TWOWORDINLINE(0x7015, 0xAA6E);
  387.  
  388. /*
  389.    AGStart
  390.    Start up Apple Guide in the background.
  391. */
  392.  
  393. EXTERN_API( AGErr )
  394. AGStart                            (void)                                                        TWOWORDINLINE(0x700A, 0xAA6E);
  395.  
  396.  
  397.  
  398. /* typedef's*/
  399.  
  400. typedef FSSpec                             AGFileFSSpecType;
  401. typedef short                             AGFileSelectorCountType;
  402. typedef short                             AGFileSelectorIndexType;
  403. typedef OSType                             AGFileSelectorType;
  404. typedef long                             AGFileSelectorValueType;
  405. typedef short                             AGFileDBType;
  406. typedef Str63                             AGFileDBMenuNamePtr;
  407. typedef short                             AGFileDBScriptType;
  408. typedef short                             AGFileDBRegionType;
  409. typedef short                             AGFileMajorRevType;
  410. typedef short                             AGFileMinorRevType;
  411. typedef short                             AGFileCountType;
  412. /* Database types (for AGFileDBType parameter).*/
  413. enum {
  414.     kAGFileDBTypeAny            = 0,
  415.     kAGFileDBTypeHelp            = 1,
  416.     kAGFileDBTypeTutorial        = 2,
  417.     kAGFileDBTypeShortcuts        = 3,
  418.     kAGFileDBTypeAbout            = 4,
  419.     kAGFileDBTypeOther            = 8
  420. };
  421.  
  422.  
  423.  
  424. EXTERN_API( OSErr )
  425. AGFileGetDBMenuName                (const FSSpec *            fileSpec,
  426.                                  Str63                     menuItemNameString);
  427.  
  428. /* Get the database type.*/
  429. EXTERN_API( OSErr )
  430. AGFileGetDBType                    (const FSSpec *            fileSpec,
  431.                                  AGFileDBType *            databaseType);
  432.  
  433. /*
  434.    Get the version of the software
  435.    that created this database.
  436. */
  437. EXTERN_API( OSErr )
  438. AGFileGetDBVersion                (const FSSpec *            fileSpec,
  439.                                  AGFileMajorRevType *    majorRev,
  440.                                  AGFileMinorRevType *    minorRev);
  441.  
  442. /* Get the database script and region information.*/
  443. EXTERN_API( OSErr )
  444. AGFileGetDBCountry                (const FSSpec *            fileSpec,
  445.                                  AGFileDBScriptType *    script,
  446.                                  AGFileDBRegionType *    region);
  447.  
  448. /* Return the number of selectors in database.*/
  449. EXTERN_API( AGFileSelectorCountType )
  450. AGFileGetSelectorCount            (const FSSpec *            fileSpec);
  451.  
  452. /*
  453.    Get the i-th database selector (1 to AGFileSelectorCountType)
  454.    and its value.
  455. */
  456. EXTERN_API( OSErr )
  457. AGFileGetSelector                (const FSSpec *            fileSpec,
  458.                                  AGFileSelectorIndexType  selectorNumber,
  459.                                  AGFileSelectorType *    selector,
  460.                                  AGFileSelectorValueType * value);
  461.  
  462. /* Return true if database is mixin.*/
  463. EXTERN_API( Boolean )
  464. AGFileIsMixin                    (const FSSpec *            fileSpec);
  465.  
  466. /*
  467.    Return the number of database files
  468.    of the specified databaseType and main/mixin.
  469.    Any file creator is acceptible,
  470.    but type must be kAGFileMain or kAGFileMixin.
  471. */
  472. EXTERN_API( AGFileCountType )
  473. AGFileGetDBCount                (short                     vRefNum,
  474.                                  long                     dirID,
  475.                                  AGFileDBType             databaseType,
  476.                                  Boolean                 wantMixin);
  477.  
  478. /*
  479.    Get the FSSpec for the dbIndex-th database
  480.    of the specified databaseType and main/mixin.
  481.    Any file creator is acceptible,
  482.    but type must be kAGFileMain or kAGFileMixin.
  483. */
  484. EXTERN_API( OSErr )
  485. AGFileGetIndDB                    (short                     vRefNum,
  486.                                  long                     dirID,
  487.                                  AGFileDBType             databaseType,
  488.                                  Boolean                 wantMixin,
  489.                                  short                     dbIndex,
  490.                                  FSSpec *                fileSpec);
  491.  
  492. /*
  493.    This selector must match with the application
  494.    creator in order for this file to appear in the 
  495.    application's Help menu. Ignored for mixin files
  496.    because they never appear in the Help menu anyway.
  497.    If empty (zeros), will appear in the Help menu
  498.    of any host application.
  499. */
  500. EXTERN_API( OSErr )
  501. AGFileGetHelpMenuAppCreator        (const FSSpec *            fileSpec,
  502.                                  OSType *                helpMenuAppCreator);
  503.  
  504. /*
  505.    This selector must match in the main and mixin
  506.    files in order for the mixin to mix-in with the main.
  507.    Empty (zeros) selectors are valid matches.
  508.    A '****' selector will mix-in with any main.
  509. */
  510. EXTERN_API( OSErr )
  511. AGFileGetMixinMatchSelector        (const FSSpec *            fileSpec,
  512.                                  OSType *                mixinMatchSelector);
  513.  
  514. /*
  515.    This is the text of the balloon for the
  516.    Help menu item for this database.
  517. */
  518. EXTERN_API( OSErr )
  519. AGFileGetHelpMenuBalloonText    (const FSSpec *            fileSpec,
  520.                                  Str255                 helpMenuBalloonString);
  521.  
  522.  
  523. EXTERN_API( OSErr )
  524. AGGetSystemDB                    (AGFileDBType             databaseType,
  525.                                  Boolean                 wantMixin,
  526.                                  FSSpec *                pFileSpec);
  527.  
  528.  
  529. #if PRAGMA_STRUCT_ALIGN
  530.     #pragma options align=reset
  531. #elif PRAGMA_STRUCT_PACKPUSH
  532.     #pragma pack(pop)
  533. #elif PRAGMA_STRUCT_PACK
  534.     #pragma pack()
  535. #endif
  536.  
  537. #ifdef PRAGMA_IMPORT_OFF
  538. #pragma import off
  539. #elif PRAGMA_IMPORT
  540. #pragma import reset
  541. #endif
  542.  
  543. #ifdef __cplusplus
  544. }
  545. #endif
  546.  
  547. #endif /* __APPLEGUIDE__ */
  548.  
  549.